home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / Utilities / Ghostscript / src / gsimage.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-01-01  |  8.5 KB  |  198 lines
  1. /* Copyright (C) 1992, 1995, 1996, 1998, 1999, 2000 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of AFPL Ghostscript.
  4.   
  5.   AFPL Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author or
  6.   distributor accepts any responsibility for the consequences of using it, or
  7.   for whether it serves any particular purpose or works at all, unless he or
  8.   she says so in writing.  Refer to the Aladdin Free Public License (the
  9.   "License") for full details.
  10.   
  11.   Every copy of AFPL Ghostscript must include a copy of the License, normally
  12.   in a plain ASCII text file named PUBLIC.  The License grants you the right
  13.   to copy, modify and redistribute AFPL Ghostscript, but only under certain
  14.   conditions described in the License.  Among other things, the License
  15.   requires that the copyright notice and this notice be preserved on all
  16.   copies.
  17. */
  18.  
  19. /*$Id: gsimage.h,v 1.2 2000/09/19 19:00:29 lpd Exp $ */
  20. /* Generic image rendering interface */
  21. /* Requires gsstate.h */
  22.  
  23. #ifndef gsimage_INCLUDED
  24. #  define gsimage_INCLUDED
  25.  
  26. #include "gsiparam.h"
  27.  
  28. /*
  29.   The API defined in this file and implemented in gsimage.c provides a
  30.   layer of buffering between clients and the underlying image processing
  31.   interface defined in gxdevcli.h (begin_[typed_]image device procedure) and
  32.   gxiparam.h (image processing procedures).
  33.  
  34.   Two of the underlying image processing procedures defined in gxiparam.h
  35.   define and process the actual data:
  36.  
  37.   - The underlying planes_wanted image processing procedure indicates which
  38.     data planes are needed (not necessarily all of them, in the case of
  39.     images with differently scaled planes), and may also change the widths
  40.     and/or depths of the planes.  It may return different results at
  41.     different times, if the widths, depths, or planes wanted changes in the
  42.     course of the image.
  43.  
  44.   - The underlying plane_data procedure actually processes the image.  Each
  45.     call of plane_data requires an integral number of scan lines for each
  46.     wanted plane.  If the widths, depths, or planes wanted vary from call to
  47.     call, plane_data may choose to accept fewer scan lines than provided.
  48.     If this happens, it is the client's responsibility to call planes_wanted
  49.     to find out which planes are now wanted, and then call plane_data again
  50.     with data for (only) the wanted planes.
  51.  
  52.   Conceptually, the gs_image_next_planes procedure defined here provides the
  53.   same function as the plane_data procedure, except that:
  54.  
  55.   - The data need not consist of complete scan lines, or be aligned in any
  56.     way;
  57.  
  58.   - If a single call passes multiple scan lines for a single plane, each
  59.     scan line is only padded to a byte boundary, not to an alignment
  60.     boundary;
  61.  
  62.   - Different amounts of data (including none) may be passed for each plane,
  63.     independent of which planes need data or the amount of data that makes
  64.     up a complete scan line for a plane;
  65.  
  66.   - The amount actually used is returned as a count of bytes used
  67.     (separately for each plane) rather than a count of scan lines.
  68.  
  69.   There is one added complication.  To avoid allocating large amounts of
  70.   storage, gs_image_next_planes may choose to copy only part of the data,
  71.   retaining the rest of it by reference.  Clients must be informed about
  72.   this, since if the data is in a stream buffer, the data may move.  To
  73.   accommodate this possibility, on subsequent calls, any data passed by the
  74.   client for a plane with retained data *replaces* the retained data rather
  75.   than (as one might expect) appending to it; if the client passes no data
  76.   for that plane, the retained data stays retained if needed.
  77.   gs_image_next_planes returns information about retained data on each call,
  78.   so the client need not keep track of it.
  79.  
  80.   The gs_image_planes_wanted procedure is analogous to planes_wanted.  It
  81.   identifies a plane as wanted if both of the following are true:
  82.  
  83.   - The underlying planes_wanted procedure says the plane is wanted.
  84.  
  85.   - Less than a full scan line of data is already buffered for that plane
  86.     (including retained data if any).
  87.  
  88.   This is not sufficient information for the PostScript interpreter for the
  89.   case where the data sources are procedures, which must be called in a
  90.   cyclic order even if they return less than a full scan line.  For this
  91.   case, the interpreter must keep track of a plane index itself, cycling
  92.   through the planes that gs_image_planes_wanted says are wanted (which may
  93.   vary from cycle to cycle).
  94.  
  95.   There is an older, simpler procedure gs_image_next that simply cycles
  96.   through the planes in order.  It does not offer the option of replacing
  97.   retained data, of passing data for more than one plane at a time, or of
  98.   passing data for planes in an arbitrary order.  Consequently, it is only
  99.   usable with image types where all planes are always wanted.  gs_image_next
  100.   should also only be used when all planes have the same width and depth and
  101.   the same amount of data is passed for each plane in a given cycle of
  102.   calls.  This is not currently checked; however, gs_image_next will give an
  103.   error if an attempt is made to pass data for a plane that has any retained
  104.   data.
  105. */
  106.  
  107. /*
  108.  * The image painting interface uses an enumeration style:
  109.  * the client initializes an enumerator, then supplies data incrementally.
  110.  */
  111.  
  112. /*
  113.  * Create an image enumerator given image parameters and a graphics state.
  114.  * This calls the device's begin_typed_image procedure with appropriate
  115.  * parameters.  Note that this is an enumerator that requires entire
  116.  * rows of data, not the buffered enumerator used by the procedures below:
  117.  * for this reason, we may move the prototype elsewhere in the future.
  118.  */
  119. #ifndef gx_image_enum_common_t_DEFINED
  120. #  define gx_image_enum_common_t_DEFINED
  121. typedef struct gx_image_enum_common_s gx_image_enum_common_t;
  122. #endif
  123.  
  124. int gs_image_begin_typed(P4(const gs_image_common_t * pic, gs_state * pgs,
  125.                 bool uses_color, gx_image_enum_common_t ** ppie));
  126.  
  127. typedef struct gs_image_enum_s gs_image_enum;
  128. gs_image_enum *gs_image_enum_alloc(P2(gs_memory_t *, client_name_t));
  129.  
  130. /*
  131.  * gs_image_init returns 1 for an empty image, 0 normally, <0 on error.
  132.  * Note that gs_image_init serves for both image and imagemask,
  133.  * depending on the value of ImageMask in the image structure.
  134.  */
  135. #ifndef gx_device_DEFINED
  136. #  define gx_device_DEFINED
  137. typedef struct gx_device_s gx_device;
  138. #endif
  139.  
  140. /* Initialize an enumerator for an ImageType 1 image. */
  141. int gs_image_init(P4(gs_image_enum * penum, const gs_image_t * pim,
  142.              bool MultipleDataSources, gs_state * pgs));
  143. /* Initialize an enumerator for a general image. */
  144. int gs_image_common_init(P5(gs_image_enum * penum,
  145.                 gx_image_enum_common_t * pie,
  146.                 const gs_data_image_t * pim,
  147.                 gs_memory_t * mem, gx_device * dev));
  148. int gs_image_enum_init(P4(gs_image_enum * penum,
  149.               gx_image_enum_common_t * pie,
  150.               const gs_data_image_t * pim, gs_state *pgs));
  151.  
  152. /*
  153.  * Return the number of bytes of data per row
  154.  * (per plane, if there are multiple planes).
  155.  */
  156. uint gs_image_bytes_per_plane_row(P2(const gs_image_enum * penum, int plane));
  157.  
  158. #define gs_image_bytes_per_row(penum)\
  159.   gs_image_bytes_per_plane_row(penum, 0)
  160.  
  161. /*
  162.  * Return a byte vector indicating which planes (still) need data for the
  163.  * current row.  See above for details.
  164.  */
  165. const byte *gs_image_planes_wanted(P1(gs_image_enum *penum));
  166.  
  167. /*
  168.  * Pass multiple or selected planes of data for an image.  See above for
  169.  * details.
  170.  *
  171.  *   plane_data[]  is an array of size num_planes of gs_const_string type
  172.  *                 which contains the pointer and the length for each.
  173.  *   used[]        is also of size num_planes and will be set to the number of
  174.  *                 bytes consumed for each plane.
  175.  *
  176.  * The amount of data available for a plane (i.e., the size of a
  177.  * plane_data[] element) can be 0 in order to provide data for a single
  178.  * plane or only some of the planes.  Note that if data is retained,
  179.  * it is not "consumed": e.g., if all of the data for a given plane is
  180.  * retained, used[] for that plane will be set to 0.
  181.  *
  182.  * Returns 1 if end of image, < 0 error code, otherwise 0.  In any case,
  183.  * stores pointers to the retained strings into plane_data[].  Note that
  184.  * used[] and plane_data[] are set even in the error or end-of-image case.
  185.  */
  186. int gs_image_next_planes(P3(gs_image_enum *penum,
  187.                 gs_const_string *plane_data,
  188.                 uint *used));
  189.  
  190. /* Pass the next plane of data for an image.  See above for details. */
  191. int gs_image_next(P4(gs_image_enum * penum, const byte * dbytes,
  192.              uint dsize, uint * pused));
  193.  
  194. /* Clean up after processing an image. */
  195. void gs_image_cleanup(P1(gs_image_enum * penum));
  196.  
  197. #endif /* gsimage_INCLUDED */
  198.